home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1996 February / EnigmA AMIGA RUN 04 (1996)(G.R. Edizioni)(IT)[!][issue 1996-02][Skylink CD III].iso / earcd / program / bgui12.lha / docs / baseclass.doc next >
Text File  |  1995-07-15  |  14KB  |  438 lines
  1.  
  2.            File: baseclass.doc
  3.     Description: Baseclass documentation.
  4.       Copyright: (C) Copyright 1994-1995 Jaba Development.
  5.              (C) Copyright 1994-1995 Jan van den Baard.
  6.              All Rights Reserved.
  7.  
  8. ------------------------------------------------------------------------------
  9.  
  10. TABLE OF CONTENTS
  11.  
  12. baseclass/--background--
  13. baseclass/Methods
  14. baseclass/Attributes
  15.  
  16. baseclass/--background--                  baseclass/--background--
  17.  
  18.     NAME
  19.     Class:        baseclass
  20.     Superclass:    GADGETCLASS
  21.     Include File:    <libraries/bgui.h>
  22.  
  23.     FUNCTION
  24.     This is the most important gadget class in BGUI.  It is the superclass
  25.     of almost all the other gadget classes at one point  or the other.  It
  26.     will take care of the following things for it's subclasses:
  27.  
  28.     o Notification
  29.     o Frames
  30.     o Labels
  31.     o Online-help.
  32.  
  33.     If you plan on writing a class for BGUI then always sub-class in  from
  34.     this class. That way you automatically    inherrit the  above  mentioned
  35.     features.
  36.  
  37. baseclass/Methods                         baseclass/Methods
  38.  
  39.     NOTE
  40.     The methods described here are also valid  for    the other  BGUI gadget
  41.     classes subclassed from this class unless documented otherwise.
  42.  
  43.     NEW METHODS
  44.     BASE_ADDMAP -- This method must be used to add a target  object to  an
  45.         object it's maplist notification  list.   Maplist notification
  46.         is  simular  to  the  notification  performed  by  the    system
  47.         "icclass" and ICA_TARGET notification.  This  method  uses the
  48.         following custom message structure:
  49.  
  50.         struct bmAddMap {
  51.             ULONG        MethodID;    /* BASE_ADDMAP */
  52.             Object           *bam_Object;  /* Target object */
  53.             struct TagItem *bam_MapList;
  54.         };
  55.  
  56.         bam_MapList --    This   can   point  to    an  array  of  TagItem
  57.         structures which contains a  set of  attributes  to map.  This
  58.         may also be NULL in which case no mapping is done.
  59.  
  60.         Returns TRUE uppon success, FALSE uppon failure.
  61.  
  62.     BASE_ADDCONDITIONAL -- This method must be used to add a target object
  63.         to an object it's conditional notification list.   Conditional
  64.         notification is a simple "if attr a == b then set attr c to d"
  65.         style of notification. Example:
  66.  
  67.         Object        *cycle, *string;
  68.  
  69.         DoMethod( cycle, BASE_ADDCONDITIONAL, string,
  70.             CYC_Active,  0,
  71.             GA_Disabled, FALSE,
  72.             GA_Disabled, TRUE );
  73.  
  74.         This  will  enable  the  string  gadget  when  the  CYC_Active
  75.         attribute  of  the  cycle  gadget  is 0.   If  the  CYC_Active
  76.         attribute is not 0 the string gadget is disabled.
  77.  
  78.         This method uses the following custom message structure:
  79.  
  80.         struct bmAddConditional {
  81.             ULONG        MethodID;   /* BASE_ADDCONDITIONAL */
  82.             Object           *bac_Object; /* Target object. */
  83.             struct TagItem    bac_Condition;
  84.             struct TagItem    bac_TRUE;
  85.             struct TagItem    bac_FALSE;
  86.         };
  87.  
  88.         bac_Condition -- This attribute pair represents  the condition
  89.             which has to be met.
  90.  
  91.         bac_TRUE -- This attribute pair is set to the target object if
  92.             the condition is TRUE (I.E. met).
  93.  
  94.         bac_FALSE -- This attribute pair is set to  the target    object
  95.             if the condition is FALSE (I.E. not met).
  96.  
  97.         Returns TRUE uppon success, FALSE uppon failure.
  98.  
  99.     BASE_ADDMETHOD -- This method must be used to  add a target  object to
  100.         an object it's method notification list.   Method notification
  101.         allows    you  to  send a  complete  method to a    target    when a
  102.         notification  event occures.   This method uses  the following
  103.         custom message structure:
  104.  
  105.         struct bmAddMethod {
  106.             ULONG        MethodID;   /* BASE_ADDMETHOD */
  107.             Object           *bam_Object; /* Target object. */
  108.             ULONG        bam_Flags;
  109.             ULONG        bam_Size;
  110.             ULONG        bam_MethodID;
  111.         };
  112.  
  113.         bam_Flags -- This may contain any of the following flags:
  114.  
  115.             BAMF_NO_GINFO -- Normally a pointer  to  a  GadgetInfo
  116.                 structure is inserted in  the method  to send.
  117.                 When this flag is set this  will not  be done.
  118.                 Please note that  when a GadgetInfo  is placed
  119.                 it is done as follows:
  120.  
  121.                 OM_NEW, OM_SET, OM_UPDATE, OM_NOTIFY -- If the
  122.                     method to  send  is  any of  these the
  123.                     GadgetInfo  is    placed    in  the  third
  124.                     long word of  the  method.  All  other
  125.                     methods will get the GadgetInfo in the
  126.                     second long word.  This  behaviour  is
  127.                     the same as with DoGadgetMethodA().
  128.  
  129.             BAMF_NO_INTERIM -- When set  the  method  will not  be
  130.                 send on interim notification events.
  131.  
  132.         bam_Size -- This field must contain the number    of  long-words
  133.             _including_ the method ID of the method to send.  This
  134.             information is needed because a copy of  the method to
  135.             send is made in an internal buffer.
  136.  
  137.         bam_MethodID -- This must be  the  ID of the  method to  send.
  138.             This  field  can  be  followed    by the method specific
  139.             data.
  140.  
  141.         Please    note   that   most  notification  will    occure on  the
  142.         input.device it's task. This means that the called method must
  143.         not  take  to  long  to  return  and  generally  should not do
  144.         anything a normal input handler should not do.
  145.  
  146.         Returns TRUE uppon success, FALSE uppon failure.
  147.  
  148.     BASE_REMMAP,  BASE_REMCONDITIONAL,   BASE_REMMETHOD,   BASE_REMHOOK --
  149.         These methods must be used to remove a target object/hook from
  150.         any of the notification lists.    This method uses the following
  151.         message structure:
  152.  
  153.         struct bmRemove {
  154.             ULONG        MethodID;   /* Any of the above. */
  155.             Object           *bar_Object; /* Object to remove. */
  156.         };
  157.  
  158.         Return code not defined.
  159.  
  160.     BASE_SETLOOP,      BASE_CLEARLOOP,     BASE_CHECKLOOP,     BASE_LEFTEXT,
  161.     BASE_SHOWHELP -- These methods are private and    should not  be of  any
  162.         use to you.
  163.  
  164.     BASE_ADDHOOK -- This method must be used to add a  hook routine to the
  165.         object it's hook-notification list.   Hook notification allows
  166.         you to add a routine via  a Hook  to the  notification    of the
  167.         object. In other words, the hook will be  called  whenever the
  168.         object    sends  out  a  notification.   This  method  uses  the
  169.         following custom message structure:
  170.  
  171.         struct bmAddHook {
  172.             ULONG        MethodID; /* BASE_ADDHOOK */
  173.             struct Hook    *bah_Hook;
  174.         };
  175.  
  176.         bah_Hook -- A pointer to the Hook structure.
  177.  
  178.         Your hook routine will be called as follows:
  179.  
  180.         rc = hookFunc( hook, obj, update );
  181.         D0           A0    A2   A1
  182.  
  183.         hook -- This will point to the Hook structure.
  184.  
  185.         obj -- This  is  a  pointer  to  the  object  that  caused the
  186.             notification.
  187.  
  188.         update -- This is a pointer to a opUpdate structure from which
  189.             you can extract data like the  visual  environment and
  190.             notified attribute changes.
  191.  
  192.         Your hook routine must return non-zero    when the  notification
  193.         caused a change of some sort and zero if not.
  194.  
  195.         Returns TRUE uppon success and FALSE uppon failure.
  196.  
  197.     SEE ALSO
  198.     intuition.library/DoGadgetMethodA(), icclass, ICA_TARGET,
  199.     utility/hooks.h
  200.  
  201.     CHANGED METHODS
  202.     OM_UPDATE -- This method fixes a bug in the system  GADGETCLASS.  Even
  203.         though the documentation states that the GA_ID    attribute of a
  204.         gadget object cannot  be  changed  by a  OM_UPDATE  message it
  205.         still does.  As this behaviour    is not    correct  the baseclass
  206.         intercepts the GA_ID  attribute  before passing  it on to  the
  207.         GADGETCLASS.  This  way  GA_ID    will  not  be  changable  by a
  208.         OM_UPDATE call.
  209.  
  210.     OM_NOTIFY -- This method will first  execute all maplist, conditional,
  211.         method and hook notification.  When that  is  done the    method
  212.         is passed onto    GADGETCLASS  for any  ICA_TARGET's that  might
  213.         still exist.
  214.  
  215.     GM_RENDER -- If this message requests a  complete  re-rendering  (I.E.
  216.         GREDRAW_REDRAW) this method will  render the  frame  and label
  217.         when available. On any other request it will simply re-compute
  218.         the gadget hitbox bounds.  When this method returns a non-NULL
  219.         value you are also allowed to render.    If this method returns
  220.         NULL then you may not render.
  221.  
  222.         Your   class  _must_  also  follow  the  same  rules.  If  the
  223.         superclass  of    your  class returns NULL you do not render and
  224.         also  return  NULL.  If the superclass of your class returns a
  225.         non-NULL  value  you  should render and also return a non-NULL
  226.         value.
  227.  
  228.         Your class must  use  the gpr_RPort field for _all_ rendering.
  229.         This usually points to a buffer rastport in  which  you render
  230.         without it showing on screen.  This  also  means  that if your
  231.         class uses OM_SET on another  object  you  must do  so without
  232.         passing the gpr_GInfo field and re-render that object later in
  233.         the RastPort pointed to by the gpr_RPort field.
  234.  
  235.         RastPort-Clipping is not allowed for BGUI objects.  The reason
  236.         for this limitation is that all rendering occures in  a buffer
  237.         rastport  without  a  layer  attached  to  it.     If your class
  238.         absolutely needs clipping you must  use the  WINDOW_NoBufferRP
  239.         or PAGE_NoBufferRP on  the window  object  or page  object  in
  240.         which the object is located.
  241.  
  242.     GM_HITTEST -- This method will return  GMR_GADGETHIT  when  the gadget
  243.         was clicked inside it's hitbox bounds.
  244.  
  245.     SEE ALSO
  246.     <intuition/gadgetclass.h>
  247.  
  248. baseclass/Attributes                      baseclass/Attributes
  249.  
  250.     NOTE
  251.     The attributes described here are also valid for the other BGUI gadget
  252.     classes subclassed from this class unless documented otherwise.
  253.  
  254.     NOTE2: ** V39 **
  255.     The following frameclass and labelclass attributes are settable on the
  256.     baseclass:
  257.  
  258.         FRM_BackPen
  259.         FRM_BackDriPen
  260.         FRM_SelectedBackPen
  261.         FRM_SelectedBackDriPen
  262.         LAB_Pen
  263.         LAB_DriPen
  264.         LAB_SelectedPen
  265.         LAB_SelectedDriPen
  266.  
  267.     Please refer to the documentation of these classes  to find  out  more
  268.     about what these attributes do.
  269.  
  270.     NAME
  271.     BT_HelpFile -- ( STRPTR )
  272.  
  273.     FUNCTION
  274.     Set the name of the file to be displayed when a  help-request  for the
  275.     object arives. Please note that the full path-name must be given.
  276.  
  277.     Default is NULL. Applicability is (IS).
  278.  
  279.     SEE ALSO
  280.     BT_HelpNode, BT_HelpLine
  281.  
  282.     NAME
  283.     BT_HelpNode -- ( STRPTR )
  284.  
  285.     FUNCTION
  286.     Set the name of the node which is diplayed in the help window.
  287.  
  288.     Default is NULL. Applicability is (IS).
  289.  
  290.     SEE ALSO
  291.     BT_HelpFile, BT_HelpLine
  292.  
  293.     NAME
  294.     BT_HelpLine - ( ULONG )
  295.  
  296.     FUNCTION
  297.     Set the line number  from  which the  file is  displayed.  This may be
  298.     useful if the help-file is not an AmigaGuide file.
  299.  
  300.     Default is 0. Applicability is (IS).
  301.  
  302.     SEE ALSO
  303.     BT_HelpFile, BT_HelpNode
  304.  
  305.     NAME
  306.     BT_HitBox - ( struct IBox * )
  307.  
  308.     FUNCTION
  309.     Get the hitbox bounds of the gadget object. This attribute is normally
  310.     only usefull for class writers.  Please  note that the contents of the
  311.     returned IBox  structure  is only  valid  _after_  you let  this class
  312.     render itself. For example suppose the    following  code is  your class
  313.     dispatcher:
  314.  
  315.     __saveds __asm ULONG
  316.     dispatcher ( __a0 Class *cl, __A2 Object *obj, __A1 Msg msg )
  317.     {
  318.         struct IBox        *domain;
  319.  
  320.         switch ( msg->MethodID ) {
  321.  
  322.             ...
  323.  
  324.             case    GM_RENDER:
  325.                 /*
  326.                 **    First let the superclass render.
  327.                 **/
  328.                 if ( ! DoSuperMethodA( cl, obj, msg ))
  329.                     return( 0L );
  330.                 /*
  331.                 **    Now you can obtain the object
  332.                 **    it's hitbox bounds.
  333.                 **/
  334.                 DoSuperMethod( cl, obj, OM_GET,
  335.                            BT_HitBox, &domain );
  336.  
  337.                 ...
  338.  
  339.                 break;
  340.         }
  341.     }
  342.  
  343.     Please note that the pointer returned is READ-ONLY.  If  you  need  to
  344.     adjust it's contents you should make a private copy of the data.
  345.  
  346.     Applicability is (G).
  347.  
  348.     NAME
  349.     BT_LabelObject, BT_FrameObject -- ( Object * )
  350.  
  351.     FUNCTION
  352.     Set or get the frame/label object to use. Normally only  class writers
  353.     use these attributes.  You can use  them to  obtain a  pointer    to the
  354.     label/frame object or to erase/change the label/frame object.  If, for
  355.     example, your class uses it's own custom rendering you can  dispose of
  356.     the baseclass frame by setting it to NULL like this:
  357.  
  358.     SetAttrs( object, FRM_FrameObject, NULL, TAG_END );
  359.  
  360.     Default  is  the  frame/label  build from the attributes passed to the
  361.     object at create time. Applicability is (SG).
  362.  
  363.     SEE ALSO
  364.     intuition.library/SetAttrs()
  365.  
  366.     NAME
  367.     BT_TextAttr -- ( struct TextAttr * )
  368.  
  369.     FUNCTION
  370.     Set/Get  the  font  which will be used by the frame and  label of  the
  371.     class. Class writers might  want  to  intercept  and  copy  this  data
  372.     before passing it onto the superclass.
  373.  
  374.     NOTE: ** V39 **
  375.           Since V39 this attribute has been made settable at  create time.
  376.           When you create an  object  with    BT_TextAttr set  the  font you
  377.           pass will be used throughout the life of    the object.  Otherwise
  378.           the  font  will  be  determined  by  the    one  you  set  in  the
  379.           windowclass.
  380.  
  381.     Default is NULL. Applicability is (ISG).
  382.  
  383.     NAME
  384.     BT_NoRecessed -- ( BOOL )
  385.  
  386.     FUNCTION
  387.     To tell the baseclass not to recess the frame when the    gadget    object
  388.     is selected. The checkboxclass uses this attribute.
  389.  
  390.     NAME
  391.     BT_LabelClick -- ( BOOL )
  392.  
  393.     FUNCTION
  394.     To  tell  the  baseclass  to  also consider clicking inside the gadget
  395.     label as a hit.
  396.  
  397.     Default is FALSE. Applicability is (I).
  398.  
  399.     SEE ALSO
  400.     Methods/GM_GADGETHIT
  401.  
  402.     NOTE
  403.     All frameclass and labelclass attributes are also valid  when creating
  404.     a baseclass object.
  405.  
  406.     NAME
  407.     BT_HelpText -- ( STRPTR)
  408.  
  409.     FUNCTION
  410.     To setup  a  text  which  will be displayed if the help-key is pressed
  411.     while the  mouse  pointer  is located above the object. This attribute
  412.     should be  used  to  attach small on-line help to the object. The text
  413.     you specify will be shown in a small BGUI_RequestA() type of requester
  414.     so you    must  make  sure  that    everything  fit's  nicely on a 600x200
  415.     screen.
  416.  
  417.     The specified text may contain any of the infoclass command sequences.
  418.  
  419.     This attribute overides the BT_HelpFile,  BT_HelpNode and  BT_HelpLine
  420.     attributes.
  421.  
  422.     Default is NULL. Applicability (IS).
  423.  
  424.     SEE ALSO
  425.     BT_HelpFile, BT_HelpNode, BT_HelpLine, infoclass/INFO_TextFormat,
  426.     bgui.library/BGUI_RequestA()
  427.  
  428.     NAME
  429.     BT_Inhibit -- ( BOOL ) ** V39 **
  430.  
  431.     FUNCTION
  432.     This attribute has been made public for people needing to know    wether
  433.     or not an object is located on a visible page.    This attribute is read
  434.     only and will read TRUE when an object is located on an invisible page
  435.     and FALSE if the object is located on a visible page.
  436.  
  437.     Applicability (G).
  438.